/*
 * Package il.ac.biu.cs.grossmm.impl.activeData
 * File NotificationProvider.java
 * 
 * This is a part of presence service framework prototype. 
 * See javadoc for more information.
 *  
 * Copyright (C) 2006 Grossmann Mark
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.

 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */
package il.ac.biu.cs.grossmm.api.flow;

import il.ac.biu.cs.grossmm.api.OperationFailedException;
import il.ac.biu.cs.grossmm.api.data.NodeType;
import il.ac.biu.cs.grossmm.api.keys.Key;
import il.ac.biu.cs.grossmm.api.keys.KeyPattern;

/**
 * An interfae which should be implemented by any data output point 
 * (notification point and publication points) implementation.
 * 
 */
public interface NotificationProvider<N> {
	/**
	 * Subscrubes a subscriber to data associated with a given key
	 * 
	 * @param key
	 *            the key which specifies the data to subscribe to, this key
	 *            must match the pattern associated with this notification
	 *            provider
	 * @param track
	 *            subscripton track. Should be null for newly created
	 *            (independent) subscription. For chained subscription should be
	 *            equal to the track of the previous subscription in the chain
	 * 
	 * @return the <tt>Subscription</tt> object if provider can handle
	 *         subscriptions for this key, <tt>null</tt> otherwise.
	 * @throws OperationFailedException
	 */
	Subscription<N> subscribe(Subscriber<N> subscriber, Key key, Track track);
	
	/**
	 * Deregisters all subscriptions for the given key. 
	 * @param key the key
	 */
	void unsubscribe(Key key);

	/**
	 * Gets node type for this notification provider.
	 * @return node type for this notification provider.
	 */
	NodeType<N> getNodeType();


	/**
	 * Gets key pattern for this notification provider
	 * @return key pattern for this notification provider
	 */
	KeyPattern getPattern();
	
	/**
	 * Gets priority of this notification provider
	 * @return priority of this notification provide
	 */
	double getPriority();
}